SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/Data::Dumper.Z/Data::Dumper

Text File | 1998-10-28 | 21.9 KB | 661 lines

     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



     NNNNAAAAMMMMEEEE
      Data::Dumper - stringified perl data structures, suitable
      for both printing and    eval

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          use Data::Dumper;

          #    simple procedural interface
          print Dumper($foo, $bar);

          #    extended usage with names
          print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);

          #    configuration variables
          {
        local $Data::Dump::Purity = 1;
        eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
          }

          #    OO usage
          $d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]);
         ...
          print $d->Dump;
         ...
          $d->Purity(1)->Terse(1)->Deepcopy(1);
          eval $d->Dump;


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      Given    a list of scalars or reference variables, writes out
      their    contents in perl syntax. The references    can also be
      objects.  The    contents of each variable is output in a
      single Perl statement.  Handles self-referential structures
      correctly.

      The return value can be evaled to get    back an    identical copy
      of the original reference structure.

      Any references that are the same as one of those passed in
      will be named    $VAR_n (where _n is a numeric suffix), and other
      duplicate references to substructures    within $VAR_n will be
      appropriately    labeled    using arrow notation.  You can specify
      names    for individual values to be dumped if you use the
      Dump() method, or you    can change the default $VAR prefix to
      something else.  See $Data::Dumper::Varname and
      $Data::Dumper::Terse below.

      The default output of    self-referential structures can    be
      evaled, but the nested references to $VAR_n will be
      undefined, since a recursive structure cannot    be constructed
      using    one Perl statement.  You should    set the    Purity flag to
      1 to get additional statements that will correctly fill in



     Page 1                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



      these    references.

      In the extended usage    form, the references to    be dumped can
      be given user-specified names.  If a name begins with    a *,
      the output will describe the dereferenced type of the
      supplied reference for hashes    and arrays, and    coderefs.
      Output of names will be avoided where    possible if the    Terse
      flag is set.

      In many cases, methods that are used to set the internal
      state    of the object will return the object itself, so    method
      calls    can be conveniently chained together.

      Several styles of output are possible, all controlled    by
      setting the Indent flag.  See    the section on _C_o_n_f_i_g_u_r_a_t_i_o_n
      _V_a_r_i_a_b_l_e_s _o_r _M_e_t_h_o_d_s below for details.

      MMMMeeeetttthhhhooooddddssss

      _P_A_C_K_A_G_E->new(_A_R_R_A_Y_R_E_F    [, _A_R_R_A_Y_R_E_F])
          Returns a    newly created Data::Dumper object.  The    first
          argument is an anonymous array of    values to be dumped.
          The optional second argument is an anonymous array of
          names for    the values.  The names need not    have a leading
          $    sign, and must be comprised of alphanumeric
          characters.  You can begin a name    with a * to specify
          that the dereferenced type must be dumped    instead    of the
          reference    itself,    for ARRAY and HASH references.

          The prefix specified by $Data::Dumper::Varname will be
          used with    a numeric suffix if the    name for a value is
          undefined.

          Data::Dumper will    catalog    all references encountered
          while dumping the    values.    Cross-references (in the form
          of names of substructures    in perl    syntax)    will be
          inserted at all possible points, preserving any
          structural interdependencies in the original set of
          values.  Structure traversal is depth-first,  and
          proceeds in order    from the first supplied    value to the
          last.

      $_O_B_J->Dump  _o_r  _P_A_C_K_A_G_E->Dump(_A_R_R_A_Y_R_E_F [, _A_R_R_A_Y_R_E_F])
          Returns the stringified form of the values stored    in the
          object (preserving the order in which they were supplied
          to new), subject to the configuration options below.  In
          an array context,    it returns a list of strings
          corresponding to the supplied values.

          The second form, for convenience,    simply calls the new
          method on    its arguments before dumping the object
          immediately.



     Page 2                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



      $_O_B_J->Dumpxs    _o_r  _P_A_C_K_A_G_E->Dumpxs(_A_R_R_A_Y_R_E_F [,    _A_R_R_A_Y_R_E_F])
          This method is available if you were able    to compile and
          install the XSUB extension to Data::Dumper. It is
          exactly identical    to the Dump method above, only about 4
          to 5 times faster, since it is written entirely in C.

      $_O_B_J->Seen([_H_A_S_H_R_E_F])
          Queries or adds to the internal table of already
          encountered references.  You must    use Reset to
          explicitly clear the table if needed.  Such references
          are not dumped; instead, their names are inserted
          wherever they are    encountered subsequently.  This    is
          useful especially    for properly dumping subroutine
          references.

          Expects a    anonymous hash of name => value    pairs.    Same
          rules apply for names as in new.    If no argument is
          supplied,    will return the    "seen" list of name => value
          pairs, in    an array context.  Otherwise, returns the
          object itself.

      $_O_B_J->Values([_A_R_R_A_Y_R_E_F])
          Queries or replaces the internal array of    values that
          will be dumped.  When called without arguments, returns
          the values.  Otherwise, returns the object itself.

      $_O_B_J->Names([_A_R_R_A_Y_R_E_F])
          Queries or replaces the internal array of    user supplied
          names for    the values that    will be    dumped.     When called
          without arguments, returns the names.  Otherwise,
          returns the object itself.

      $_O_B_J->Reset
          Clears the internal table    of "seen" references and
          returns the object itself.

      FFFFuuuunnnnccccttttiiiioooonnnnssss

      Dumper(_L_I_S_T)
          Returns the stringified form of the values in the    list,
          subject to the configuration options below.  The values
          will be named $VAR_n in the output, where _n is a numeric
          suffix.  Will return a list of strings in    an array
          context.

      DumperX(_L_I_S_T)
          Identical    to the Dumper()    function above,    but this calls
          the XSUB implementation.    Only available if you were
          able to compile and install the XSUB extensions in
          Data::Dumper.





     Page 3                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



      CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn    VVVVaaaarrrriiiiaaaabbbblllleeeessss oooorrrr MMMMeeeetttthhhhooooddddssss

      Several configuration    variables can be used to control the
      kind of output generated when    using the procedural
      interface.  These variables are usually localized in a block
      so that other    parts of the code are not affected by the
      change.

      These    variables determine the    default    state of the object
      created by calling the new method, but cannot    be used    to
      alter    the state of the object    thereafter.  The equivalent
      method names should be used instead to query or set the
      internal state of the    object.

      The method forms return the object itself when called    with
      arguments, so    that they can be chained together nicely.

      $Data::Dumper::Indent     _o_r  $_O_B_J->Indent([_N_E_W_V_A_L])
          Controls the style of indentation.  It can be set    to 0,
          1, 2 or 3.  Style    0 spews    output without any newlines,
          indentation, or spaces between list items.  It is    the
          most compact format possible that    can still be called
          valid perl.  Style 1 outputs a readable form with
          newlines but no fancy indentation    (each level in the
          structure    is simply indented by a    fixed amount of
          whitespace).  Style 2 (the default) outputs a very
          readable form which takes    into account the length    of
          hash keys    (so the    hash value lines up).  Style 3 is like
          style 2, but also    annotates the elements of arrays with
          their index (but the comment is on its own line, so
          array output consumes twice the number of    lines).     Style
          2    is the default.

      $Data::Dumper::Purity     _o_r  $_O_B_J->Purity([_N_E_W_V_A_L])
          Controls the degree to which the output can be evaled to
          recreate the supplied reference structures.  Setting it
          to 1 will    output additional perl statements that will
          correctly    recreate nested    references.  The default is 0.

      $Data::Dumper::Pad  _o_r  $_O_B_J->Pad([_N_E_W_V_A_L])
          Specifies    the string that    will be    prefixed to every line
          of the output.  Empty string by default.

      $Data::Dumper::Varname  _o_r  $_O_B_J->Varname([_N_E_W_V_A_L])
          Contains the prefix to use for tagging variable names in
          the output. The default is "VAR".

      $Data::Dumper::Useqq    _o_r  $_O_B_J->Useqq([_N_E_W_V_A_L])
          When set,    enables    the use    of double quotes for
          representing string values.  Whitespace other than space
          will be represented as [\n\t\r], "unsafe"    characters
          will be backslashed, and unprintable characters will be



     Page 4                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



          output as    quoted octal integers.    Since setting this
          variable imposes a performance penalty, the default is
          0.  The Dumpxs() method does not honor this flag yet.

      $Data::Dumper::Terse    _o_r  $_O_B_J->Terse([_N_E_W_V_A_L])
          When set,    Data::Dumper will emit single, non-self-
          referential values as atoms/terms    rather than
          statements.  This    means that the $VAR_n names will    be
          avoided where possible, but be advised that such output
          may not always be    parseable by eval.

      $Data::Dumper::Freezer  _o_r  $_O_B_J->Freezer([_N_E_W_V_A_L])
          Can be set to a method name, or to an empty string to
          disable the feature.  Data::Dumper will invoke that
          method via the object before attempting to stringify it.
          This method can alter the    contents of the    object (if,
          for instance, it contains    data allocated from C),    and
          even rebless it in a different package.  The client is
          responsible for making sure the specified    method can be
          called via the object, and that the object ends up
          containing only perl data    types after the    method has
          been called.  Defaults to    an empty string.

      $Data::Dumper::Toaster  _o_r  $_O_B_J->Toaster([_N_E_W_V_A_L])
          Can be set to a method name, or to an empty string to
          disable the feature.  Data::Dumper will emit a method
          call for any objects that    are to be dumped using the
          syntax bless(DATA, CLASS)-_M_E_T_H_O_D()>.  Note that this
          means that the method specified will have    to perform any
          modifications required on    the object (like creating new
          state within it, and/or reblessing it in a different
          package) and then    return it.  The    client is responsible
          for making sure the method can be    called via the object,
          and that it returns a valid object.  Defaults to an
          empty string.

      $Data::Dumper::Deepcopy  _o_r  $_O_B_J->Deepcopy([_N_E_W_V_A_L])
          Can be set to a boolean value to enable deep copies of
          structures.  Cross-referencing will then only be done
          when absolutely essential    (i.e., to break    reference
          cycles).    Default    is 0.

      $Data::Dumper::Quotekeys  _o_r    $_O_B_J->Quotekeys([_N_E_W_V_A_L])
          Can be set to a boolean value to control whether hash
          keys are quoted.    A false    value will avoid quoting hash
          keys when    it looks like a    simple string.    Default    is 1,
          which will always    enclose    hash keys in quotes.

      $Data::Dumper::Bless    _o_r  $_O_B_J->Bless([_N_E_W_V_A_L])
          Can be set to a string that specifies an alternative to
          the bless    builtin    operator used to create    objects.  A
          function with the    specified name should exist, and



     Page 5                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



          should accept the    same arguments as the builtin.
          Default is bless.

      EEEExxxxppppoooorrrrttttssss

      Dumper

     EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
      Run these code snippets to get a quick feel for the behavior
      of this module.  When    you are    through    with these examples,
      you may want to add or change    the various configuration
      variables described above, to    see their behavior.  (See the
      testsuite in the Data::Dumper    distribution for more
      examples.)

          use Data::Dumper;

          package Foo;
          sub new {bless {'a' => 1,    'b' => sub { return "foo" }}, $_[0]};

          package Fuz;             # a weird REF-REF-SCALAR object
          sub new {bless \($_ = \ 'fu\'z'),    $_[0]};

          package main;
          $foo = Foo->new;
          $fuz = Fuz->new;
          $boo = [ 1, [], "abcd", \*foo,
               {1 => 'a', 023 => 'b', 0x45 => 'c'},
               \\"p\q\'r", $foo, $fuz];

          ########
          #    simple usage
          ########

          $bar = eval(Dumper($boo));
          print($@)    if $@;
          print Dumper($boo), Dumper($bar);     # pretty print    (no array indices)

          $Data::Dumper::Terse = 1;         # don't output    names where feasible
          $Data::Dumper::Indent = 0;     # turn    off all    pretty print
          print Dumper($boo), "\n";

          $Data::Dumper::Indent = 1;     # mild    pretty print
          print Dumper($boo);

          $Data::Dumper::Indent = 3;     # pretty print    with array indices
          print Dumper($boo);








     Page 6                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



          $Data::Dumper::Useqq = 1;         # print strings in double quotes
          print Dumper($boo);


          ########
          #    recursive structures
          ########

          @c = ('c');
          $c = \@c;
          $b = {};
          $a = [1, $b, $c];
          $b->{a} =    $a;
          $b->{b} =    $a->[1];
          $b->{c} =    $a->[2];
          print Data::Dumper->Dump([$a,$b,$c], [qw(a b c)]);


          $Data::Dumper::Purity = 1;     # fill    in the holes for eval
          print Data::Dumper->Dump([$a, $b], [qw(*a    b)]); #    print as @a
          print Data::Dumper->Dump([$b, $a], [qw(*b    a)]); #    print as %b


          $Data::Dumper::Deepcopy =    1;     # avoid cross-refs
          print Data::Dumper->Dump([$b, $a], [qw(*b    a)]);


          $Data::Dumper::Purity = 0;     # avoid cross-refs
          print Data::Dumper->Dump([$b, $a], [qw(*b    a)]);


          ########
          #    object-oriented    usage
          ########

          $d = Data::Dumper->new([$a,$b], [qw(a b)]);
          $d->Seen({'*c' =>    $c});         # stash a ref without printing    it
          $d->Indent(3);
          print $d->Dump;
          $d->Reset->Purity(0);         # empty the seen cache
          print join "----\n", $d->Dump;


          ########
          #    persistence
          ########

          package Foo;
          sub new {    bless {    state => 'awake' }, shift }
          sub Freeze {
          my $s    = shift;
          print    STDERR "preparing to sleep\n";



     Page 7                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



          $s->{state} =    'asleep';
          return bless $s, 'Foo::ZZZ';
          }

          package Foo::ZZZ;
          sub Thaw {
          my $s    = shift;
          print    STDERR "waking up\n";
          $s->{state} =    'awake';
          return bless $s, 'Foo';
          }

          package Foo;
          use Data::Dumper;
          $a = Foo->new;
          $b = Data::Dumper->new([$a], ['c']);
          $b->Freezer('Freeze');
          $b->Toaster('Thaw');
          $c = $b->Dump;
          print $c;
          $d = eval    $c;
          print Data::Dumper->Dump([$d], ['d']);


          ########
          #    symbol substitution (useful for    recreating CODE    refs)
          ########

          sub foo {    print "foo speaking\n" }
          *other = \&foo;
          $bar = [ \&other ];
          $d = Data::Dumper->new([\&other,$bar],['*other','bar']);
          $d->Seen({ '*foo'    => \&foo });
          print $d->Dump;


     BBBBUUUUGGGGSSSS
      Due to limitations of    Perl subroutine    call semantics,    you
      cannot pass an array or hash.     Prepend it with a \ to    pass
      its reference    instead.  This will be remedied    in time, with
      the arrival of prototypes in later versions of Perl.    For
      now, you need    to use the extended usage form,    and prepend
      the name with    a * to output it as a hash or array.

      Data::Dumper cheats with CODE    references.  If    a code
      reference is encountered in the structure being processed,
      an anonymous subroutine that contains    the string '"DUMMY"'
      will be inserted in its place, and a warning will be printed
      if Purity is set.  You can eval the result, but bear in mind
      that the anonymous sub that gets created is just a
      placeholder.    Someday, perl will have    a switch to cache-on-
      demand the string representation of a    compiled piece of



     Page 8                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))



      code,    I hope.     If you    have prior knowledge of    all the    code
      refs that your data structures are likely to have, you can
      use the Seen method to pre-seed the internal reference table
      and make the dumped output point to them, instead.  See the
      _E_X_A_M_P_L_E_S manpage above.

      The Useqq flag is not    honored    by Dumpxs() (it    always outputs
      strings in single quotes).

      SCALAR objects have the weirdest looking bless workaround.

     AAAAUUUUTTTTHHHHOOOORRRR
      Gurusamy Sarathy      [e-mail]

      Copyright (c)    1996-98    Gurusamy Sarathy. All rights reserved.
      This program is free software; you can redistribute it
      and/or modify    it under the same terms    as Perl    itself.

     VVVVEEEERRRRSSSSIIIIOOOONNNN
      Version 2.09      (9 July 1998)

     SSSSEEEEEEEE AAAALLLLSSSSOOOO
      _p_e_r_l(1)
































     Page 9                        (printed 10/23/98)






     DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333)))) 22223333////JJJJuuuullll////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222))))  DDDDaaaattttaaaa::::::::DDDDuuuummmmppppeeeerrrr((((3333))))























































     Page 10                        (printed 10/23/98)